Over 1,000 Windows 95 Programs/Over 1000 Windows 95 Programs (Microforum) (Disc 1).iso/0626/base64.txt

Text File | 1997-04-06 | 22KB | 538 lines

Documentation for the Base64 Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Contents:
~~~~~~~~~

1. General information regarding the programs
2. About ENCODE64.EXE
  + Examples
  + Forming header string(s)
3. About DECODE64.EXE
  + Examples / Multi-part decoding help
4. About UNIX2DOS.COM
5. Technical information regarding BASE-64 encoding
6. Disclaimer, Distribution, About the Author, etc.
7. Registration Information
8. Revision Notes

The only requirement for any of these programs is DOS for ENCODE64
and DECODE64, and Windows 3.1 or above for SHELL2 (it will also work
on Windows '95).

For information on SHELL2.EXE, refer to SHELL2.TXT.

Find other good programs like this one at my home page:

   http://www.geocities.com/SiliconValley/Park/3056/

Support Shareware: Register!


1. General:
~~~~~~~~~~~
  These DOS programs have built-in error checking to make sure the files
are processed correctly. However, if there are unexplained errors while
processing, the program will give a "Runtime Error" message. Check in
this documentation for information regarding possible errors. Most errors
will likely be caused by the DECODE64 program, because of text-processing
problems. If all else fails, refer to the section on DECODE64 and see
how the program works! If you think a certain problem may be a bug in
the program, please e-mail me. My e-mail address is at the bottom of
this file.

  NOTE: DECODE64 will ONLY decode files with a CR/LF at the end of every
line, so it will not decode UNIX text files. A (freeware) utility I wrote
was included with these programs, called UNIX2DOS. See the section on
UNIX2DOS.EXE for information on how to use it.

  REGARDING E-MAIL: Internet mail programs will almost definitely not
recognize encoded files over e-mail when encoded using ENCODE64. This
is because information is added to the header and body of sent e-mails
when files are included with them. It is impossible to mimic this with
these programs. Whoever receives a Base64 encoded file encoded using
ENCODE64 may need a utility similar to DECODE64 to be able to decode
it. (This is especially true when using multiple-part encoding & decoding.)


2. About ENCODE64.EXE:
~~~~~~~~~~~~~~~~~~~~~~
  This program takes any file (binary or otherwise) and converts it
into a format transmittable over the Internet. (See technical information
below.) The command line for this program is:

ENCODE64 <input filename> [output filename] [/M<number>] [/O] [/P]
         [/B<boundary>] [/H<header>]

Items in <> are necessary, in [] are optional.

Where <filename> is any file. [Output filename] is optional, but if you
do give it, ENCODE64 will attempt to use that file name instead of the
generic ".64" filename.

/B<boundary> --> Make your own "boundary" string inside of the encoded
files. This is more advanced and will probably not need to be used unless
you're using ENCODE64.EXE with an e-mail program.

/H<header> --> Lets you form your own header. This is an advanced
option; see the end of this section for more information.

/O --> When you use this option, the program will AUTOMATICALLY attempt
to overwrite any files it needs to, without having a (Y/N) prompt. Use
this carefully.

/M --> Tell ENCODE64 to do a multiple-file output. A number should
immediately follow, telling ENCODE64 how many kilobytes (KB) of
data should be put into each file. 1 kilobyte is slightly less than
20 lines of data. The program will tell you if the number of kilobytes you
specified is too out of range for the particular file you are encoding.
The maximum number of files ENCODE64 will output to is 99 (for filename
reasons). Use the Base64 Windows Shell program for easier multi-part
encoding.

/P --> Turn on a percentage meter which tells how far through ENCODE64
is. For single files, it will show how far it is so far. For multiple
files, it will show how far through it is for the particular file it
is working on. (The last file it creates may not reach 100%)

* Examples: *
~~~~~~~~~~~~~

C:\>ENCODE64 PROGRAM.ZIP

After executing this, ENCODE64 will create a file called "PROGRAM.64" in
the current directory. If a file with that name was already found, it will
say so and will not overwrite it (it must be moved or deleted before
ENCODE64 will create the file, just to make sure that no data is lost).

C:\>ENCODE64 PROGRAM.ZIP PROG.TXT

ENCODE64 will attempt to make a file called PROG.TXT instead of the
generic PROGRAM.64. It will ask you if you wish to overwrite it if
it already exists.

C:\>ENCODE64 PROGRAM.ZIP PROG.TXT /M20 /O /P

ENCODE64 will attempt to make multiple files until the end of PROGRAM.ZIP
is reached. It will start with PROG01.TXT, put 20 kilobytes of encoded data
in it (approx. 400 lines of data), then move on to PROG02.TXT. If it
encountered PROG01.TXT already, it will automatically overwrite it because
the "/O" option was put on the command line. It will also have a percentage
meter which will show how far it is through each one of the files it
creates.


* Forming your own header strings *
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you are using ENCODE64 with an e-mail system, you may need to do
this to make other programs recognize files encoded using ENCODE64.EXE.
Since the command line cannot accept <CR/LF> characters (for line breaks),
you will need to use the following special characters:

% -- Insert filename.
^ -- Insert CR/LF.
# -- Insert space.

This would be a generic header:

 -hContent-Disposition:#attachment;#filename="%"
 ^Content-Transfer-Encoding:#BASE64
 ^Content-Type:#application/octet-stream

(Note that I split up into three sections what would normally be a
single string on the command line.)

If this header string were used, the header that appears at the top
of encoded files would appear like this:

 Content-Disposition: attachment; filename="anyfile.zip"
 Content-Transfer-Encoding: BASE64
 Content-Type: application/octet-stream


3. About DECODE64.EXE:
~~~~~~~~~~~~~~~~~~~~~~
This part of the documentation may seem a little complex, but the
only really necessary command-line option is the first: the input file
which contains the encoded data.

Command line for this program is:

DECODE64 <input file/file mask> [output file] [/M] [/O] [/K] [/L]

Items in <> are necessary, in [] are optional.

Where <input filename> is any Base64-encoded file.

/O --> Tell DECODE64 to automatically erase any files it needs to
without prompting you. Be careful when using this switch that you
do not overwrite any important files.

/K --> Tell DECODE64 to NOT Keep reading through a Base64-
encoded file until all files are decoded out of it. If you want it to
stop scanning the file after the first file is decoded, or if you know
that the encoded file only contains one file to decode, then use this.
It will speed up processing because DECODE64 won't need to keep
searching.

[output filename] --> DECODE64 will use this instead of the filename
it finds inside the Base64-encoded file(s). When using the "/M" option,
DECODE64 will use the filename it finds in the first Base64-encoded
file it scans.

/M --> Tell the program to accept input from more than one file. If
you use this, you should use a <filename mask> instead of a single
<input filename>. The mask should use generic DOS wildcard characters
such as '*' and '?'. Use the "DIR" command to make sure the files are
in the correct order before decoding. (See examples below.)

/L --> Tell DECODE64 to decode multiple encoded files, one at a time,
using a <file mask>. This (obviously) does not work with "/M". The
[output file] option does not work with this. "/K" is automatically
activated by the program when this switch is used, meaning that only
the first file located in each encoded file will be decoded, and
decoding will stop in each file as soon as the first file is finished.
(See examples below.)

At the top of every multiple-part file created by ENCODE64, it tells what
part number the current file is, and how many parts there are totally.
This first number can be used to create the correct filename for decoding
multiple-part files, if you receive them in different e-mails. (Otherwise
there may not be a way to tell which file comes first, second, etc.) Note
that DECODE64 is *not* able to read this header automatically, since it
does not know which files are made with which encoder.

DECODE64 will automatically right- and left-justify all lines of encoded
data.

* Examples: *
~~~~~~~~~~~~~

C:\>DECODE64 PROGRAM.64 PROG.ZIP

Running it with this command line will make DECODE64 attempt to
decode PROGRAM.64, and, instead of using the file name it finds in
PROGRAM.64, it will use the filename PROG.ZIP to output to.

-
C:\>DECODE64 PROGRAM.64 PROG.ZIP /O

If PROG.ZIP already exists, DECODE64 will erase it without prompting.
-

C:\>DECODE64 PROG*.64 PROG.ZIP /M /O

DECODE64 will use the filename mask "PROG*.64" and use those files to
output to PROG.ZIP. DECODE64 will discard whatever filename it finds
in the PROG*.64 files, and use the name "PROG.ZIP" instead. If PROG.ZIP
already exists, DECODE64 will erase it without prompting. Be careful
when using the /M option -- use "DIR" before running DECODE64 to make
sure your files are in the correct order. Such as:

PROG01.64
PROG02.64
PROG03.64
   ...

This would be ideal. This is the order that ENCODE64 puts files in.

-
C:\>DECODE64 *.64 /L

This would decode all files with the ".64" extension, one at a time.
-

The ideal format for the BASE 64 file would be one created by the
ENCODE64 program, or in this format:

--==========================
name="test.zip"
<header stuff>
<header stuff>

AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJKKKKLLLLMMMMNNNNOOOOPPPP
QQ==
--==========================

Note the blank line between the header and the encoded data, and the
"-" character immediately following the encoded data. This will make
sure the file is created properly.

If there is no blank space between the header and the encoded data,
the program will keep reading until it reaches a blank line, causing
errors.

If the file ends immediately after the encoded data, DECODE64 will give
an error message ("Possible unexpected end of file"), but will
nevertheless create the file correctly. It is recommended that there
be a line starting with a dash (-) immediately following the data.

About the "Bad Character" error: This error is caused by a character
other than the ones accepted by Base64 being in the encoded data. This
error will not halt the program, but the outputted file may have bad
data in it. If the end of the encoded data was not properly found,
this error could also be caused by DECODE64 attempting to decode
regular text which may appear after the encoded file segment.

Most other errors may be caused by DECODE64 not being able to properly
find the end of the encoded data. For best results, edit the encoded
file so it matches the template shown above.


4. About UNIX2DOS.COM:
~~~~~~~~~~~~~~~~~~~~~~
  I included this program in the archive so that users who have a UNIX
e-mail system can also use the Base64 encoder and decoder. The program
will convert any generic UNIX-type text file to the DOS CR/LF standard.
The command line is simple:

UNIX2DOS <input filename>

Where <input filename> is the name of any UNIX-type text file.

This program will not harm DOS-type text files if they are processed.


5. Technical Information:
~~~~~~~~~~~~~~~~~~~~~~~~~
  BASE-64 (MIME encoding) converts regular 8-bit encoded files into
a form which can be readily transmittable via Internet e-mail. It
is impossible to send any 8-bit file over e-mail without this or a
similar process done (such as XX-encoding, UU-encoding, etc).
  The way it encodes is by taking three (8-bit) bytes from the file,
and converting those 24 bits into 4 sets of 6-bit numbers. Since a
6-bit number can never go over 63, it outputs to the BASE-64 file
with these characters:

Character:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
Value:    0..............................................................63

  Since all files will not have sizes evenly divisible by three, padding
is added with the "=" character at the end of the BASE64-encoded data.

  BASE-64 is superior to UU encoding & XX encoding in that it does not
use any characters that may *not* be readily transmittable via Internet.
Also, for every 45 encoded characters of XX & UU, there is one extra
character as a line checksum (seen as the first character of every
line). Data transmission has become so reliable that checksums are
no longer necessary.
  For more information on MIME encoding, look up RFC 1521. (This and
other files can be downloaded off my homepage. See the URL at the top
of this document or by running ENCODE64 or DECODE64.)


6. Disclaimer, Distribution, About the Author, Etc.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  DISCLAIMER: I'm not responsible if this messes up your computer in
any way. But how could it? :)

  If you enjoy using this, or use it a lot, please register! Since I
have spent WAY too much of my life updating this program and providing
support to users, I have "upgraded" this from freeware to shareware.
(There are 400+ lines of code in DECODE64 alone!)

  If there are any persistent problems with either of the programs which
you think are bugs, e-mail me.

  These programs can be distributed freely as long as ALL of the original
files are kept in the same archive, not modified in any way, and no
other programs can be put into the same archive with these. (See
VENDOR.TXT) If these programs are put on a CD-ROM, FTP site, WWW, BBS,
etc, I'd appreciate knowing it! Also, none of the programs can be sold.

  Thanks go to the few people who have written me and convinced me to
bring out future versions with revisions and improvements, and to those
who have written just to thank me! :)

My e-mail address is: [e-mail]
If that doesn't work: [e-mail]

My homepage (great place!):

         http://www.geocities.com/SiliconValley/Park/3056/


7. Registration information
~~~~~~~~~~~~~~~~~~~~~~~~~~~
  As you may have noticed, I have not added anything to the program to
cripple it, or any "nags". (Except for a small registration notice at
the beginning of the program. :) I've also been giving out a lot of
technical support to many, many users!

  So, if you use this program a lot, please e-mail me for registration
information. (Especially important for companies!)

  You can request a registration form by writing to me at the address
below. Registration is just $15^ for the three programs (ENCODE64,
DECODE64, and the always useful SHELL2). Just $5 each + of course, you
get UNIX2DOS for free.

My e-mail address is: [e-mail]
If that doesn't work: [e-mail]


^ -- A company site license is extra.


8. Revision Updates
~~~~~~~~~~~~~~~~~~~
 These notes tell of features, etc, added to the programs after the
 first release. The programs themselves don't tell their own version
 number, but if this document was included with your archive, then you
 have the updated version.

 Sorry, no fancy version numbers. Can only make filename eight
 characters!

--\
#1|--> Basic version. Didn't even support more than one command line
--/     option. :(  After a lot of tracking down, I even found a copy
        of it!

--\
#2|--> 1. First update.
--/
       2. Support for using the 'name = <filename>' string instead of
           'name="<filename>"' string. (Used by some encoders.)

       3. User can now optionally overwrite files: either the Base64
           files created by ENCODE64 or the files created by DECODE64.

       4. Support for some encoders, which, instead of having dashes
           ("-") immediately following encoded data, will terminate
           with a blank line. If DECODE64 finds a blank line anywhere
           in encoded data, it will stop processing.

--\
#3|--> Basically re-wrote the entire program.
--/
       1. User can now enter two filenames on the command line, one
           specifying the input file, and one the output file. For
           ENCODE64, you can specify the file name to use instead of
           the generic ".64" file; with DECODE64, you can specify
           which file name to use instead of the one found in the
           header of the file DECODE64 decodes.

       2. Fast, Assembler character search routine added to DECODE64.

       3. Corrected error of DECODE64: it left one or both files open if
           an error occurred during processing.

       4. /O option added to command line. This will force the programs
           to automatically attempt to overwrite any files they create,
           without making a (Y/N) prompt to ask you if you want it
           overwritten. ***USE CAREFULLY*** (So as to not overwrite
           important data.)

       5. /M option added. For ENCODE64, this will allow the output of
           more than one Base64 file; for DECODE64, this will allow
           the input of more than one Base64 file into one larger file.
           (When using with DECODE64, it requires a filename mask instead
           of an input filename.)

       6. Programs themselves have become more helpful -- I've added
           better help and error notices. Just run the programs with
           no command line to see the help.

       7. Added more efficient code to both ENCODE64 and DECODE64. Nearly
           doubled the math speed of ENCODE64.

--\
#4|--> 1. Included the file utility UNIX2DOS with the archive. It will
--/        convert UNIX text files to DOS format, which is used by
           ENCODE64 & DECODE64. It will not harm DOS text files if they
           are accidentally processed.

       2. Percentage meter added to ENCODE64, activated by the "/P"
           command-line parameter. For single-file encoding, it will
           tell you how far through it is. For multiple file encoding,
           it will tell how far complete it is on the single file it
           is working on. (The last file it creates may not reach 100%)

       3. ENCODE64 tells how many files it will create before it starts
           processing.

       4. Added code to ENCODE64 for faster string concatenation. Over
           double the speed of the old routine.

       5. ENCODE64 now, instead of using number of lines as the basis
           for multi-part encoding, will use kilobytes instead.

       6. SHELL64 program added to archive; Windows program to make
           encoding and decoding files easier, especially for multiple
           files. It is the first version, so there may be some bugs
           to iron out.

       7. "Text/plain" in header of encoded files has been changed to
            "application/octet-stream" for compatibility with mail
            programs.

--\
#5|--> 1. ENCODE64 has gotten even faster AND smaller. A miracle of
--/        modern programming efficiency. :)

       2. DECODE64 can now decode more than one file out of a single
           Base64-encoded file, using the "/K" option.

       3. ENCODE64 changed so last boundary marker leaves extra two
           dashes ("--") for more compatibility with MIME. Also, there
           is now an empty line between the last line of encoded data
           and the last boundary marker.

       4. Another option added to DECODE64 -- "/L". With this, many
           files can be decoded at once using a <file mask>. Useful
           for batch files and e-mail programs!

       5. DECODE64 will now "intelligently" scan for the filename in
           the header. It will look for anything between two quotes
           and anything coming after the "=" symbol. (Not just for the
           two 'name = ' and 'name="' strings.) It is much more
           compatible with e-mail programs.

       6. UNIX2DOS has been re-written entirely in Assembler for more
           speed. Therefore, it doesn't really have that many options,
           and is only safe when used properly. On the other hand,
           it is faster and much smaller!

--\
#6|--> 1. UNIX2DOS re-written. VERY fast.
--/
       2. Support for new Content-Disposition header. Hopefully this
           won't mess up any e-mail programs.

       3. You can define your own boundary marker now. Good for using
           ENCODE64 with e-mail systems.

       4. 386 Assembler code added for more speed. Still not very fast,
           but what can you expect from Pascal?

       5. Headers can be defined on the command line.

       6. Small error using ENCODE64 with Shell64 -- the pause after the
           program runs would sometimes mess things up a bit.

--\
#7|--> 1. Shell64 reincarnated as Shell2.
--/
       2. 386 code being taken out of version #6. Wasn't worth not letting
           the program be run on 286 and slower computers for such a
           minimal gain in speed.

       3. Big bugs in the original Shell64 which are fixed in Shell2.
           Probably more, but I can't find everything!

       4. Updated Shell2's faulty PIF files.

       5. Fixed bug with ENCODE64's and DECODE64's (undocumented) "/W"
           command-line option, which is only used by Shell2. I think
           it's actually a bug with the TP compiler I use, but I fixed
           it by adding Assembler code that does nearly the same thing.
           This bug would cause ENCODE64 and DECODE64, when used with
           SHELL2, to produce an error by Windows which would alert the
           user to re-boot the computer.

       6. Bug with using DECODE64 with SHELL2 - Shell2 would put the
           file it decodes into the wrong directory. Fixed!
__________________________________________________________________________
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~